IDLWAVE User Manual: Online Help

4.3 Online Help

For IDL system routines, extensive documentation is supplied with IDL. IDLWAVE can access the HTML version of this documentation very quickly and accurately, based on the local context. This can be much faster than using the IDL online help application, because IDLWAVE usually gets you to the right place in the documentation directly—e.g., a specific keyword of a routine—without any additional browsing and scrolling.

For this online help to work, an HTML version of the IDL documentation is required. Beginning with IDL 6.2, HTML documentation is distributed directly with IDL, along with an XML-based catalog of routine information. By default, IDLWAVE automatically attempts to convert this XML catalog into a format Emacs can more easily understand, and caches this information in your idlwave_config_directory (~/.emacs.d/idlwave/, by default). It also re-scans the XML catalog if it is newer than the current cached version. You can force rescan with the menu entry IDLWAVE->Routine Info->Rescan XML Help Catalog.

Before IDL 6.2, the HTML help was not distributed with IDL, and was not part of the standalone IDLWAVE distribution, but had to be downloaded separately. This is no longer necessary: all help and routine information is supplied with IDL versions 6.2 and later.

There are a variety of options for displaying the HTML help: see below. Help for routines without HTML documentation is also available, by using the routine documentation header and/or routine source.

In any IDL program (or, as with most IDLWAVE commands, in the IDL Shell), press M-? (idlwave-context-help), or click with S-mouse-3 to access context sensitive online help. The following locations are recognized context for help:

Routine names	The name of a routine (function, procedure, method).
Keyword Parameters	A keyword parameter of a routine.
System Variables	System variables like `!DPI`.
System Variable Tags	System variables tags like `!D.X_SIZE`.
IDL Statements	Statements like `PRO`, `REPEAT`, `COMPILE_OPT`, etc.
IDL Controls	Control structures like `FOR`, `SWITCH`, etc.
Class names	A class name in an `OBJ_NEW` call.
Class Init Keywords	Beyond the class name in an `OBJ_NEW` call.
Executive Command	An executive command like `.RUN`. Mostly useful in the shell.
Structure Tags	Structure tags like `state.xsize`
Class Tags	Class tags like `self.value`.
Default	The routine that would be selected for routine info display.

Note that the OBJ_NEW function is special in that the help displayed depends on the cursor position. If the cursor is on the ‘OBJ_NEW’, this function is described. If it is on the class name inside the quotes, the documentation for the class is pulled up. If the cursor is after the class name, anywhere in the argument list, the documentation for the corresponding Init method and its keywords is targeted.

Apart from an IDLWAVE buffer or shell, there are two more places from which online help can be accessed.

Online help for routines and keywords can be accessed through the Routine Info display. Click with mouse-3 on an item to see the corresponding help (see Routine Info).
When using completion and Emacs pops up a *Completions* buffer with possible completions, clicking with mouse-3 on a completion item invokes help on that item (see Completion). Items for which help is available in the online system documentation (vs. just the program source itself) will be emphasized (e.g., colored blue).

In both cases, a blue face indicates that the item is documented in the IDL manual, but an attempt will be made to visit non-blue items directly in the originating source file.